Almathera Ten Pack 3: CDPD 3/Almathera Ten on Ten - Disc 3: CDPD3.iso/scope/151-175/scopedisk165/filesysinfo/fsi.doc

Text File | 1995-03-19 | 9KB | 170 lines

                                    FSI

                  A comprehensive File System Information
                utility for the Amiga created by Ray Lambert


    FSI is pure public domain software.  No fee is expected but the author
would like the source code and documentation to remain with the executable
program when passed around.



Overview.

    FSI has three purposes in life:  1) To aid beginning AmigaDOS users in
learning and understanding how the Amiga's filing system works; 2) to allow
experienced users to explore the devices in their system, revealing
information for debugging or informational uses; and 3) to aid programmers
in learing and understanding how they can 'smartly' interface their programs
with AmigaDOS.
    The beginning AmigaDOS user can use FSI to identify names of things that
are found in the filing system.  For instance, a beginning user who doesn't
yet understand how ASSIGN works may be confused by logical names such as
"S:", which (usually) refers to a directory called "S" on their Workbench
disk.  They may not understand why they can refer to their boot Workbench
disk as either "DF0:", "Workbench1.3:" or "SYS:".  They may wonder what
those names are that appear under the icons on the Workbench screen.  Any of
these names can be given to FSI.  FSI will identify what they are and what
they refer to, hopefully providing some insight as to how they work
together.
    For more experienced users, FSI will provide information about filing
system devices which may be difficult or impossible to obtain by other
means, including low-level information such as the parameters which are
usually set through 'MountList' entries.
    While no formal documentation is included which explains how or why the
tricks used in this program work, it is hoped that the source code (and
comments therein) will 'speak for itself', thereby fulfilling purpose number
three.  Some initial knowledge of AmigaDOS data structures and operations
will be required to understand the source code.  If you have trouble with
it, "The AmigaDOS Manual 2nd Edition" (published by Bantam Computer Books,
666 Fifth Avenue, NY, NY, 10103), pages 268 through 277 is a very good place
to start.  You should also read and understand the following Amiga-C header
files:  <libraries/dos.h>, <libraries/dosextens.h> and
<libraries/filehandler.h>.  FSI will certainly not provide a complete
understanding as to how AmigaDOS works, but it will hopefully provide some
insight into the 'dark secrets' in AmigaDOS, and should reveal how to
perform tasks and get information that may be neccessary for some software.
I know I learned a lot by wrting FSI.



Using FSI.

    FSI is extremely simple to use and is best learned through actual use.
Try typing "FSI DF0" for an example.

    CLI usage: FSI [-x] <device|volume|assign|file|directory name> [...]

    Include -x if you want extended device information.

    [...] indicates that multiple parameters are allowed.

    FSI does not work from Workbench (sorry :)



Disclaimer.

    The following disclaimer is provided mainly for programmers who would
study the source code to FSI.  Those of you who are not programmers have
nothing to fear from what is said below.  Those of you who are programmers
are advised to please read the following as it is a very important aside to
the source code:

    FSI works by accessing global AmigaDOS data structures.  While it is
supported to make use of these structures, it is so only if you properly
protect yourself when you do so.  FSI does not!  'Properly protecting
yourself' has nothing to do with condoms or AIDS.  Rather, it means that you
must block other tasks from using these data structures while you are using
them, through the use of the Forbid()/Permit() functions.  If you have
already looked at the source code to FSI, you will have noticed that FSI
_does_ use Forbid() and Permit(), but it does not use them correctly.

    First let me explain why FSI is written as such.  FSI started-out as an
experiment -- a vessal to allow me to explore the way in which these file
structures are used.  I wanted to perform tasks such as determining what
volume (if any) is currently mounted in DF0:, or, if a DF1: drive exists in
the system, or, if some volume name (maybe that a user gave me) actually
exists and/or if it is a filing system device or not.  In the end, I learned
how to combine the information in the structures to obtain the information
that I really needed.  FSI is like a poorly planned house which had many
rooms added to it over the course of time with little thought as to their
placement, resulting in an architect's nightmare and an eyesore.  By the
time I was finished with FSI, it had grown into something somewhat large and
complex, something requiring a complete re-write to make it conform to the
rules.  This was out-of-the-question however, because it would simply take
too long to do and I had already gotten out of it what I had needed.  So,
thus it remains: a mere hack.

    FSI performs a Forbid() while it is looping through the AmigaDOS device
list, and a Permit() when the loop is over.  However, it then has the nasty
habit of holding pointers that it acquired during the loop and re-using
them.  This is where it violates the rules.  After the Permit() is
performed, multi-tasking is once again enabled, thereby allowing other
programs to access the device list.  Some of these programs may alter the
contents of nodes found in the list, maybe even deleting some.  If a node is
deleted, any pointers to that node held by nasty programs like FSI suddenly
become invalid.  In the worst case, FSI will spew some junk into your CLI
window, or lock-up in an endless loop due to bad pointers -- the guru should
never be summoned because FSI _NEVER_ modifies any of the structures, but
rather only attempts to print the text and numbers it finds in them.
    The proper way to implement a program such as FSI would be to code it in
two stages: 1) scan the lists in a Forbid()den state making COPIES of all the
structures and data that will be needed to create the display; and 2)
generate the display from the copies that where made in stage 1.  Note that
it is absolutely NOT acceptable to simply Forbid() at the beginning of the
program and Permit() at the end.  This is because the act of printing to the
CLI temporarily cancels the effect of your Forbid() call!  'How is this?'
you may ask... well, let me explain... printing to the CLI involves at
least two levels of message passing (the Write() command sends a message to
the device handler and most handlers will then send a message to a .device
to perform the actual I/O) and, when a message is sent to perform
synchronous I/O, a Wait() must be performed.  If a task Forbid()'s and then
Wait()'s, the Wait() cancels the Forbid().  If this didn't happen a deadlock
would result (think about it, Wait() suspends your task, yet you've
forbidden all other tasks from running as well!).  When Wait() returns your
Forbid() is once again in effect, but in the interim another task could have
modified the global data.  A simple example of this is: your task is
printing to the CLI, the user presses the space bar (blocking all output to
the console), opens another CLI (if not already open), and issues an ASSIGN
command to de-assign some logical name.  Bang.  Your pointers are no good!
    Regardless of FSI's disregard for the rules, I felt that the information
provided within may still be exetremely useful to some of you, and so I have
released it as is.  Also, because FSI _NEVER_ writes to any of the data
structures, there is virtually no chance of it causing a guru, so it is
reasonably safe to use.  (This dissertation should be sufficient to convince
you that I don't normally write nasty programs like this and that this is an
exception which I am not at all proud of :] )

    The moral of all this is DON'T WRITE PROGRAMS LIKE FSI!  Follow the
rules so that Amiga software will be solid and trustworthy thereby keeping
the Amiga's image strong and prospering!



Acknowledgment.

    I would like to acknowledge the help of Douglas R. Merritt through the
source code for his "devinfo" program, especially for showing me how
DLT_DEVICE and DLT_VOLUME nodes are related via the dn_Task field.



Get to know me!

    If you have questions, suggestions, flames, propositions, etc., I can be
reached at the following places:

PLink:        Analog*Kid    (log on often)

BIX:          AnalogKid     (log on sparsely)

U.S. Snail:   Ray Lambert
              PO Box 1253
              Westport, Massachusetts  02790

Phone:        [phone]